home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / libraries / patchlibv3.lha / patchlibrary / docs / Patch.man < prev   
Text File  |  1994-08-13  |  8KB  |  203 lines
  1. patch.library V3.50 manual:
  2.  
  3.  
  4. MOTIVATION:
  5.  
  6.     The idea for this library came up to me, when I recently wrote some
  7.     programs, which patch into library functions.
  8.  
  9.  
  10.  
  11. FEATURES:
  12.  
  13. - In general patch.library offers you an easy way of installing and removing
  14.   your own patches for library functions.
  15.  
  16. - Patch.library checks, if your patch can safely be removed (e.g.: when no
  17.   other task is running in the patchcode).
  18.  
  19. - In general patches may only be removed in LIFO order. Patch.library
  20.   provides a mechanism that allows you to remove any patch you installed
  21.   with patch.library any time.
  22.  
  23. - In addition it provides you a priority system, which allows you to specify
  24.   the sequence of the patches, if more than one patch has to be installed for
  25.   one library function.
  26.  
  27. - Patch.library also provides you a way to check, if your patch is already
  28.   installed by supplying a name field for every patch.
  29.  
  30. - Patch.library automatically flushes caches from Kick V37.xxx on, so software
  31.   that uses patch.library will continue to work on systems with an 68040 or ....
  32.  
  33. - With patch.library you have no problems patching pre-V36 dos.library
  34.   functions, since patch.library automatically detects these nonstandard
  35.   functions and takes the appropriate steps to patch these functions.
  36.  
  37. - The tasks using the patch may be limited to certain tasknames and/or taskIDs.
  38.  
  39. - But always remember that installing and especially removing patches can never
  40.   be coded without any risk of crashing the machine. Although patch.library does
  41.   everything possible to minimize the chances of a crash, do not use its functions
  42.   without good care (e.g. minimize the number of install and remove operations)
  43.  
  44.  
  45.  
  46. NEWS FOR V2:
  47. - New functions for V2:
  48.    * RemovePatchTags()
  49.     replaces the obsolete functions RemovePatch() and WaitRemovePatch()
  50.     patches can now be removed ANY TIME
  51.    * InstallPatchTags()
  52.     replaces the obsolete function InstallPatch()
  53.     patching of libraries, devices and resources is now possible
  54. - Many of the internal structures have been made public, so the lists may be
  55.   scanned by application programs. Note that these structures were rearranged
  56.   for V2, so make sure that at least patch.library V2 is installed.
  57.   Also make sure to use the semaphore protection, when scanning these lists.
  58. - Some bugs have been removed and a few possible locking problems have been solved.
  59.  
  60.  
  61.  
  62. NEWS FOR V3:
  63. - New functions for V3:
  64.    * FindPatchTags()
  65.     can be used instead of the old FindPatch() function, but takes a
  66.     taglist as parameter for future enhancements.
  67.    * SetPatch()
  68.     Makes it possible to limit the tasks, which will use a patch.
  69.     (e.g.: A OpenWindow() function patch will only apply, if CygnusED opens
  70.     a window / A DisplayBeep() function patch will be used for all
  71.     tasks, but not for the task, which has the TaskID $007c835a).
  72.     Some other attributes of a patch may also be set.
  73.    * GetPatch()
  74.     This function will, return some attributes and lists of a patch.
  75.    * PatchFreeVec()
  76.     Frees memory returned by GetPatch().
  77.  
  78.  
  79. ABOUT PATCHCODES:
  80.  
  81. The patchcode you install must obey these rules:
  82. - Patchcodes MUST be reentrant! (i.e. library-functions can always be used
  83.   by multiple tasks at the same time)
  84. - Patchcodes MUST preserve ALL registers!
  85.   (If replacing a library function a valid returncode must be set as documented
  86.   in the Autodocs)
  87. - Patchcodes MUST be pc-relative, if NewCodeSize > 0!
  88. - Patchcodes should use as little stack as possible, because tasks using your code
  89.   may otherwise run out of stack.
  90. - Patchcodes can be ended either with the rts-instruction, which is the normal
  91.   method, or with the FALLBACK macro provided in 'Patch.i'.
  92.   The FALLBACK macro allows You to end the patch and execute the original
  93.   library function, if you replaced the library function (Priority = 0).
  94.   The FALLBACK macro functions like a 'rts'-instruction, if Priority <> 0.
  95.  
  96.  
  97.  
  98. NOTES & WARNINGS:
  99.  
  100. - Some library functions use in-line code (e.g.: exec.library/GetCC() )
  101.   Patching these functions will always fail.
  102. - It's up to your patchroutines to preserve the registers.
  103. - There is always a chance (very small) that memory will be deallocated, while
  104.   instructions from it will still executed (-> crash).
  105. - Patching functions will use some stack (at least 4 Bytes) from programs
  106.   calling the patched function. This might crash the machine, if a program
  107.   has only a very small stack reserve.
  108. - The patches should be written in assembler - support for C-patches is currently
  109.   not provided, but it should be possible to write the appropriate stub.
  110.  
  111.  
  112.  
  113. MORE PROGRAMMER INFOS:
  114.  
  115. can be found in the accompanying file 'patch.doc' and in the example programs.
  116.  
  117.  
  118.  
  119. FUTURE PLANS:
  120. - Create AmigaGuide documentations.
  121. - Write a program, that works similar to SaferPatches, but uses patch.library.
  122. - Write a commodity similar to the Commodity Exchange program that allows
  123.     manipulations of the IncludeTask, ExcludeTask lists of the patches
  124.     and a way to load and save these settings (already under development).
  125. - Program more applications using the patch.library.
  126.  
  127.  
  128.  
  129. EXAMPLES:
  130.  
  131. The package includes two programs with assembler source to show you how
  132. to use the patch.library:
  133.  
  134. 1. CPUClr:
  135.     Installs a patch routine for graphics.library/BltClear(), which
  136.     uses the CPU instead of the BLITTER to clear Chipmem.
  137.     It shows how easy and save it can be to install and remove a patch,
  138.     without wasting memory or CPU time.
  139.     With the program CPUClrTEST you can check how much faster memory
  140.     clearing becomes.
  141.     For more informations about CPUClr see CPUClr.doc.
  142.  
  143. 2. ShowNeededFiles:    (Simple SnoopDos)
  144.     Installs some patch routines to monitor dos.library/Open(),
  145.     Lock() and LoadSeg() functions. It shows how the priority system
  146.     of patch.library works.
  147.     Note that this program works with all versions of the dos.library. 
  148.     Break this program with CTRL-C.
  149.  
  150.  
  151.  
  152. LICENSE:
  153.  
  154. This material is © Copyright 1993/94 by Stefan Fuchs. All rights reserved.
  155.  
  156. It may be distributed freely as long as the following restrictions are met:
  157.  
  158. - The distributor may charge a fee to recover distribution costs.
  159.   The fee for diskette distribution should not be more than
  160.   the cost to obtain the same diskette from Fred Fish.
  161.  
  162. - The distributor agrees to cease distributing the programs and
  163.   data involved if requested to do so by the author.
  164.  
  165. - You may copy and distribute verbatim copies of the program's
  166.   executable code and documentation as you receive it, in any
  167.   medium, provided that you conspicuously and appropriately
  168.   publish only the original, unmodified program, with all
  169.   copyright notices and disclaimers of warranty intact and
  170.   including all the accompanying documentation, example files and
  171.   anything else that came with the original.
  172.  
  173. - If you are interested in including any of this material in a commercial
  174.   product, you should contact the author for his permission.
  175.  
  176. - The author will not be liable for any damage arising from the
  177.   failure of the programs or the library to perform as described,
  178.   or any destruction of other programs using the library residing
  179.   on a system. While I know of no damaging errors, the user of this
  180.   package uses it at his or her own risk.
  181.  
  182.  
  183. This package may be distributed in PD-series (e.g.: the Fred Fish library)!
  184.  
  185.  
  186. CONTACT:
  187.  
  188.     To contact the author for bugreports, hints, ideas, donations, ....
  189.     write to:
  190.  
  191.  
  192.     Stefan Fuchs                 E-Mail: snfuchs@lsd.nbg.sub.org
  193.     Oskar-von-Miller-Str. 49
  194.  
  195.     D - 90478 Nürnberg
  196.     GERMANY
  197.  
  198.  
  199. AND FINALLY:
  200.     If You use patch.library in any of your projects, please sent me a copy,
  201.     of your program, so i can make sure that everything works fine with
  202.     future versions of patch.library.
  203.